[docs] GtkCalendar: Move documentation to inline comments

Fixes https://bugzilla.gnome.org/show_bug.cgi?id=617389

Signed-off-by: Javier Jardón <jjardon@gnome.org>

diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 996aa553b9573c23edea355a4055c7c2e647f5de..c1980434082cac6f927685473299d07e7cf2cea6 100644 (file)
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -2,6 +2,7 @@ gtkbbox.sgml
 gtkbox.sgml
 gtkbuilder.sgml
 gtkbutton.sgml
+gtkcalendar.sgml
 gtkhbox.sgml
 gtkiconview.sgml
 gtkmessagedialog.sgml

diff --git a/docs/reference/gtk/tmpl/gtkcalendar.sgml b/docs/reference/gtk/tmpl/gtkcalendar.sgml
deleted file mode 100644 (file)
index 4c117a6..0000000
--- a/docs/reference/gtk/tmpl/gtkcalendar.sgml
+++ /dev/null
@@ -1,315 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkCalendar
-
-<!-- ##### SECTION Short_Description ##### -->
-Displays a calendar and allows the user to select a date
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-#GtkCalendar is a widget that displays a calendar, one month at a time. 
-It can be created with gtk_calendar_new().
-</para>
-<para>
-The month and year currently displayed can be altered with 
-gtk_calendar_select_month(). The exact day can be selected from the displayed 
-month using gtk_calendar_select_day().
-</para>
-<para>
-To place a visual marker on a particular day, use gtk_calendar_mark_day() 
-and to remove the marker, gtk_calendar_unmark_day().
-Alternative, all marks can be cleared with gtk_calendar_clear_marks().
-</para>
-<para>
-The way in which the calendar itself is displayed can be altered using
-gtk_calendar_set_display_options().
-</para>
-<para>
-The selected date can be retrieved from a #GtkCalendar using
-gtk_calendar_get_date().
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkCalendar ##### -->
-<para>
-<structfield>num_marked_dates</structfield> is an integer containing the
-number of days that have a mark over them.
-</para>
-<para>
-<structfield>marked_date</structfield> is an array containing the day numbers
-that currently have a mark over them.
-</para>
-<para>
-<structfield>month</structfield>, <structfield>year</structfield>, and 
-<structfield>selected_day</structfield> contain the currently visible month,
-year, and selected day respectively.
-</para>
-<para>
-All of these fields should be considered read only, and everything in this
-struct should only be modified using the functions provided below.
-</para>
-<note>
-<para>
-Note that <structfield>month</structfield> is zero-based (i.e it allowed values
-are 0-11) while <structfield>selected_day</structfield> is one-based
-(i.e. allowed values are 1-31). 
-</para>
-</note>
-
-
-<!-- ##### SIGNAL GtkCalendar::day-selected ##### -->
-<para>
-Emitted when the user selects a day.
-</para>
-
-@calendar: the object which received the signal.
-
-<!-- ##### SIGNAL GtkCalendar::day-selected-double-click ##### -->
-<para>
-
-</para>
-
-@calendar: the object which received the signal.
-
-<!-- ##### SIGNAL GtkCalendar::month-changed ##### -->
-<para>
-Emitted when the user clicks a button to change the selected month on a
-calendar.
-</para>
-
-@calendar: the object which received the signal.
-
-<!-- ##### SIGNAL GtkCalendar::next-month ##### -->
-<para>
-
-</para>
-
-@calendar: the object which received the signal.
-
-<!-- ##### SIGNAL GtkCalendar::next-year ##### -->
-<para>
-
-</para>
-
-@calendar: the object which received the signal.
-
-<!-- ##### SIGNAL GtkCalendar::prev-month ##### -->
-<para>
-
-</para>
-
-@calendar: the object which received the signal.
-
-<!-- ##### SIGNAL GtkCalendar::prev-year ##### -->
-<para>
-
-</para>
-
-@calendar: the object which received the signal.
-
-<!-- ##### ARG GtkCalendar:day ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkCalendar:detail-height-rows ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkCalendar:detail-width-chars ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkCalendar:month ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkCalendar:no-month-change ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkCalendar:show-day-names ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkCalendar:show-details ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkCalendar:show-heading ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkCalendar:show-week-numbers ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkCalendar:year ##### -->
-<para>
-
-</para>
-
-<!-- ##### USER_FUNCTION GtkCalendarDetailFunc ##### -->
-<para>
-
-</para>
-
-@calendar: 
-@year: 
-@month: 
-@day: 
-@user_data: 
-@Returns: 
-
-
-<!-- ##### ENUM GtkCalendarDisplayOptions ##### -->
-<para>
-</para>
-
-@GTK_CALENDAR_SHOW_HEADING: 
-@GTK_CALENDAR_SHOW_DAY_NAMES: 
-@GTK_CALENDAR_NO_MONTH_CHANGE: 
-@GTK_CALENDAR_SHOW_WEEK_NUMBERS: 
-@GTK_CALENDAR_WEEK_START_MONDAY: 
-@GTK_CALENDAR_SHOW_DETAILS: 
-
-<!-- ##### FUNCTION gtk_calendar_new ##### -->
-<para>
-</para>
-
-@void: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_calendar_select_month ##### -->
-<para>
-</para>
-
-@calendar: 
-@month: 
-@year: 
-
-
-<!-- ##### FUNCTION gtk_calendar_select_day ##### -->
-<para>
-</para>
-
-@calendar: 
-@day: 
-
-
-<!-- ##### FUNCTION gtk_calendar_mark_day ##### -->
-<para>
-</para>
-
-@calendar: 
-@day: 
-
-
-<!-- ##### FUNCTION gtk_calendar_unmark_day ##### -->
-<para>
-</para>
-
-@calendar: 
-@day: 
-
-
-<!-- ##### FUNCTION gtk_calendar_clear_marks ##### -->
-<para>
-</para>
-
-@calendar: 
-
-
-<!-- ##### FUNCTION gtk_calendar_get_display_options ##### -->
-<para>
-
-</para>
-
-@calendar: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_calendar_set_display_options ##### -->
-<para>
-
-</para>
-
-@calendar: 
-@flags: 
-
-
-<!-- ##### FUNCTION gtk_calendar_get_date ##### -->
-<para>
-</para>
-
-@calendar: 
-@year: 
-@month: 
-@day: 
-
-
-<!-- ##### FUNCTION gtk_calendar_set_detail_func ##### -->
-<para>
-
-</para>
-
-@calendar: 
-@func: 
-@data: 
-@destroy: 
-
-
-<!-- ##### FUNCTION gtk_calendar_get_detail_width_chars ##### -->
-<para>
-
-</para>
-
-@calendar: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_calendar_set_detail_width_chars ##### -->
-<para>
-
-</para>
-
-@calendar: 
-@chars: 
-
-
-<!-- ##### FUNCTION gtk_calendar_get_detail_height_rows ##### -->
-<para>
-
-</para>
-
-@calendar: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_calendar_set_detail_height_rows ##### -->
-<para>
-
-</para>
-
-@calendar: 
-@rows: 
-
-

diff --git a/gtk/gtkcalendar.c b/gtk/gtkcalendar.c
index 0b456e6e84afde538f48d1123c495835ab912707..bd8cfdc5029db58f4ffcafb1bf6264641b37e2ad 100644 (file)
--- a/gtk/gtkcalendar.c
+++ b/gtk/gtkcalendar.c
@@ -29,6 +29,29 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+/**
+ * SECTION:gtkcalendar
+ * @Short_description: Displays a calendar and allows the user to select a date
+ * @Title: GtkCalendar
+ *
+ * #GtkCalendar is a widget that displays a calendar, one month at a time. It
+ * can be created with gtk_calendar_new().
+ *
+ * The month and year currently displayed can be altered with
+ * gtk_calendar_select_month(). The exact day can be selected from the displayed
+ * month using gtk_calendar_select_day().
+ *
+ * To place a visual marker on a particular day, use gtk_calendar_mark_day() and
+ * to remove the marker, gtk_calendar_unmark_day(). Alternative, all marks can
+ * be cleared with gtk_calendar_clear_marks().
+ *
+ * The way in which the calendar itself is displayed can be altered using
+ * gtk_calendar_set_display_options().
+ *
+ * The selected date can be retrieved from a #GtkCalendar using
+ * gtk_calendar_get_date().
+ */
+
 #include "config.h"
 
 #ifdef HAVE_SYS_TIME_H
@@ -579,6 +602,13 @@ gtk_calendar_class_init (GtkCalendarClass *class)
                                                         TRUE,
                                                         GTK_PARAM_READWRITE));
 
+  /**
+   * GtkCalendar::month-changed:
+   * @calendar: the object which received the signal.
+   *
+   * Emitted when the user clicks a button to change the selected month on a
+   * calendar.
+   */
   gtk_calendar_signals[MONTH_CHANGED_SIGNAL] =
     g_signal_new (I_("month-changed"),
                  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -587,6 +617,13 @@ gtk_calendar_class_init (GtkCalendarClass *class)
                  NULL, NULL,
                  _gtk_marshal_VOID__VOID,
                  G_TYPE_NONE, 0);
+
+  /**
+   * GtkCalendar::day-selected:
+   * @calendar: the object which received the signal.
+   *
+   * Emitted when the user selects a day.
+   */
   gtk_calendar_signals[DAY_SELECTED_SIGNAL] =
     g_signal_new (I_("day-selected"),
                  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -595,6 +632,13 @@ gtk_calendar_class_init (GtkCalendarClass *class)
                  NULL, NULL,
                  _gtk_marshal_VOID__VOID,
                  G_TYPE_NONE, 0);
+
+  /**
+   * GtkCalendar::day-selected-double-click:
+   * @calendar: the object which received the signal.
+   *
+   * Emitted when the user double-clicks a day.
+   */
   gtk_calendar_signals[DAY_SELECTED_DOUBLE_CLICK_SIGNAL] =
     g_signal_new (I_("day-selected-double-click"),
                  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -603,6 +647,13 @@ gtk_calendar_class_init (GtkCalendarClass *class)
                  NULL, NULL,
                  _gtk_marshal_VOID__VOID,
                  G_TYPE_NONE, 0);
+
+  /**
+   * GtkCalendar::prev-month:
+   * @calendar: the object which received the signal.
+   *
+   * Emitted when the user switched to the previous month.
+   */
   gtk_calendar_signals[PREV_MONTH_SIGNAL] =
     g_signal_new (I_("prev-month"),
                  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -611,6 +662,13 @@ gtk_calendar_class_init (GtkCalendarClass *class)
                  NULL, NULL,
                  _gtk_marshal_VOID__VOID,
                  G_TYPE_NONE, 0);
+
+  /**
+   * GtkCalendar::next-month:
+   * @calendar: the object which received the signal.
+   *
+   * Emitted when the user switched to the next month.
+   */
   gtk_calendar_signals[NEXT_MONTH_SIGNAL] =
     g_signal_new (I_("next-month"),
                  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -619,6 +677,13 @@ gtk_calendar_class_init (GtkCalendarClass *class)
                  NULL, NULL,
                  _gtk_marshal_VOID__VOID,
                  G_TYPE_NONE, 0);
+
+  /**
+   * GtkCalendar::prev-year:
+   * @calendar: the object which received the signal.
+   *
+   * Emitted when user switched to the previous year.
+   */
   gtk_calendar_signals[PREV_YEAR_SIGNAL] =
     g_signal_new (I_("prev-year"),
                  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -627,6 +692,13 @@ gtk_calendar_class_init (GtkCalendarClass *class)
                  NULL, NULL,
                  _gtk_marshal_VOID__VOID,
                  G_TYPE_NONE, 0);
+
+  /**
+   * GtkCalendar::next-year:
+   * @calendar: the object which received the signal.
+   *
+   * Emitted when user switched to the next year.
+   */
   gtk_calendar_signals[NEXT_YEAR_SIGNAL] =
     g_signal_new (I_("next-year"),
                  G_OBJECT_CLASS_TYPE (gobject_class),